Ask Composer's autoloaders for the file instead of letting them include it - #6431

AutoloadSourceLocator finds which file declares a class by running the registered autoloaders behind FileReadTrapStreamWrapper, which records the path an include reached for and serves an empty script in its place. That only shadows the real file while the compiler asks the wrapper for the contents. When OPcache already holds the script, it does not ask, and the file runs a second time:

Child process error (exit code 255): Fatal error: Cannot redeclare function Psl\Type\optional()
(previously declared in C:\myProject\vendor\php-standard-library\type\src\Psl\Type\optional.php:18)
in C:\myProject\vendor\php-standard-library\type\src\Psl\Type\optional.php on line 18

That is fatal for any file that declares a function, which is how php-standard-library and azjezz/psl lay out their code: one function per file. Their files-autoload bootstrap has already loaded every path that their PSR-4 prefix also resolves to.

2.2.13 exposed this by starting spawned workers with OPcache on (ProcessHelper::resolveWorkerIniEntries()), and it still reproduces on 2.3.1. Windows has no pcntl_fork(), so its workers are always spawned.

Fix

Before an autoloader that is a Composer ClassLoader runs inside the trap, AutoloadSourceLocator asks its findFile() for the path. findFile() answers with the same path loadClass() would include, without running anything, so nothing is compiled and no cache is consulted. The check sits in the existing loop over the autoloaders, so registration order is unchanged, and every other autoloader still runs in the trap as before.

findFile() joins the mapped prefix to the rest of the name, so its answer can contain ../ segments and mixed separators. It is resolved with realpath(), as an include would resolve it, because locateIdentifier() compares the located path with ReflectionClass::getFileName().

A path behind a stream wrapper is left to the trap, because realpath() cannot resolve it. The phar's own autoloader is such a ClassLoader: it maps PHPStan\ to phar://.../src.

In the phar

php-scoper prefixes the new use Composer\Autoload\ClassLoader;, but Box leaves the class itself unprefixed, so in the phar the instanceof would never match. compiler/build/scoper.inc.php already removes that prefix in a fixed list of files, and AutoloadSourceLocator.php is now on that list.

Checksum PHAR is expected to fail, because this PR changes how that one file is scoped.

Tests

e2e/bug-15184 has the same layout as the report: a function-per-file module loaded through Composer's files autoload, in a directory its PSR-4 prefix also maps, and code that uses the function's name as a class. It runs with --debug and with pcntl_fork disabled. Forked workers switch OPcache off, so a default run on Linux would not reach the bug. On Windows, the spawned-worker run crashes with Cannot redeclare function on 2.3.x and passes with this PR.

The phar case needs no new test: the existing extension-tests jobs cover it. They failed with Call to method yes() on an unknown class PHPStan\TrinaryLogic. on an earlier revision of this PR that had no fallback for paths behind a stream wrapper.

Also checked by hand on Windows with PHP 8.5, against a project on php-standard-library/type that analyses return $o instanceof \Psl\Type\optional;:

• the 2.3.1 phar: Cannot redeclare function Psl\Type\optional()
• this PR from source: class.notFound on the instanceof line, no fatal

Alternatives considered

Earlier revisions of this PR kept the include and tried to make it safe. The first called opcache_invalidate() from the trap's stream_open() for the path being opened. Its CI run was cut short by the next push, so it was neither confirmed nor ruled out. The next refused the open for a file already in get_included_files(), and failed the Symplify integration job.

#6742 invalidates every included file before any autoloader runs, which also covers autoloaders that are not a Composer ClassLoader. This PR does not cover those. The two approaches could be combined, with invalidation only before the autoloaders that are not a ClassLoader.

Closes phpstan/phpstan#15184

🤖 Generated with Claude Code